home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / Tcl_TraceVar.man < prev    next >
Encoding:
Text File  |  1990-07-31  |  9.7 KB  |  267 lines
  1.  
  2.  
  3.  
  4. Tcl_TraceVar      Tcl Command Language Library       Tcl_TraceVar
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_TraceVar,  Tcl_UnTraceVar,  Tcl_VarTraceInfo  -  monitor
  12.      accesses to a variable
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ttccll..hh>>
  16.  
  17.      int
  18.      TTccll__TTrraacceeVVaarr((_i_n_t_e_r_p, _v_a_r_N_a_m_e, _g_l_o_b_a_l, _f_l_a_g_s, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a))
  19.  
  20.      TTccll__UUnnTTrraacceeVVaarr((_i_n_t_e_r_p, _v_a_r_N_a_m_e, _g_l_o_b_a_l))
  21.  
  22.      int
  23.      TTccll__VVaarrTTrraacceeIInnffoo((_i_n_t_e_r_p, _v_a_r_N_a_m_e, _g_l_o_b_a_l, _p_r_o_c_P_t_r, _c_l_i_e_n_t_D_a_t_a_P_t_r))
  24.  
  25. AARRGGUUMMEENNTTSS
  26.      Tcl_Interp   *_i_n_t_e_r_p          (in)      Interpreter contain-
  27.                                              ing variable.
  28.  
  29.      char         *_v_a_r_N_a_m_e         (in)      Name of variable.
  30.  
  31.      int          _g_l_o_b_a_l           (in)      If  non-zero,   then
  32.                                              treat   _v_a_r_N_a_m_e   as
  33.                                              global     variable,
  34.                                              ignoring  any active
  35.                                              Tcl        procedure
  36.                                              frames.    If  zero,
  37.                                              look up variable  in
  38.                                              current  procedure's
  39.                                              context.
  40.  
  41.      int          _f_l_a_g_s            (in)      OR-ed combination of
  42.                                              the           values
  43.                                              TCL_TRACE_READS,
  44.                                              TCL_TRACE_WRITES,
  45.                                              and
  46.                                              TCL_TRACE_DELETES.
  47.                                              Indicates      which
  48.                                              operations are to be
  49.                                              traced.
  50.  
  51.      char         *((*_p_r_o_c)())     (in)      Procedure to  invoke
  52.                                              whenever  one of the
  53.                                              traced    operations
  54.                                              occurs.
  55.  
  56.      ClientData   _c_l_i_e_n_t_D_a_t_a       (in)      Arbitrary   one-word
  57.                                              value   to  pass  to
  58.                                              _p_r_o_c.
  59.  
  60.  
  61.  
  62.  
  63. Sprite v.1.0         Printed:  July 31, 1990                    1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_TraceVar      Tcl Command Language Library       Tcl_TraceVar
  71.  
  72.  
  73.  
  74.      char         *((**_p_r_o_c_P_t_r)()) (out)     Pointer to  word  in
  75.                                              which    to    store
  76.                                              address  of  current
  77.                                              trace  procedure for
  78.                                              _v_a_r_N_a_m_e, if any.
  79.  
  80.      ClientData   *_c_l_i_e_n_t_D_a_t_a_P_t_r   (out)     Pointer to  word  in
  81.                                              which    to    store
  82.                                              ClientData       for
  83.                                              current   trace  for
  84.                                              _v_a_r_N_a_m_e, if any.
  85.  
  86. _________________________________________________________________
  87.  
  88.  
  89. DDEESSCCRRIIPPTTIIOONN
  90.      TTccll__TTrraacceeVVaarr allows an arbitrary C procedure  to  be  inter-
  91.      posed in the access path to a variable, so that all reads or
  92.      writes to that variable are mediated by the procedure.   The
  93.      _f_l_a_g_s  argument  to  TTccll__TTrraacceeVVaarr indicates which operations
  94.      are to cause _p_r_o_c to be invoked;  it consists  of  an  OR-ed
  95.      combination of any of the following values:
  96.  
  97.      TTCCLL__TTRRAACCEE__RREEAADDSS
  98.           Invoke _p_r_o_c whenever an attempt is  made  to  read  the
  99.           variable.
  100.  
  101.      TTCCLL__TTRRAACCEE__WWRRIITTEESS
  102.           Invoke _p_r_o_c whenever an attempt is made to  modify  the
  103.           variable.
  104.  
  105.      TTCCLL__TTRRAACCEE__DDEELLEETTEESS
  106.           Invoke _p_r_o_c whenever  the  trace  on  the  variable  is
  107.           removed.  This can happen either because TTccll__UUnnTTrraacceeVVaarr
  108.           is called, or because the variable was deleted (e.g. it
  109.           is a local variable and the procedure is returning).
  110.  
  111.      If the  trace  is  created  successfully  then  TTccll__TTrraacceeVVaarr
  112.      returns TCL_OK.  If an error occurred (e.g. there is already
  113.      a trace set on the variable) then TCL_ERROR is returned  and
  114.      an error message will be left in _i_n_t_e_r_p->_r_e_s_u_l_t.
  115.  
  116.      Whenever one of the specified operations occurs,  _p_r_o_c  will
  117.      be invoked.  It should have the following structure:
  118.           char *
  119.           _p_r_o_c(_c_l_i_e_n_t_D_a_t_a, _i_n_t_e_r_p, _v_a_r_N_a_m_e, _g_l_o_b_a_l, _f_l_a_g_s, _o_l_d_V_a_l_u_e, _n_e_w_V_a_l_u_e)
  120.                ClientData _c_l_i_e_n_t_D_a_t_a;
  121.                Tcl_Interp *_i_n_t_e_r_p;
  122.                char *_v_a_r_N_a_m_e;
  123.                int _g_l_o_b_a_l;
  124.                int _f_l_a_g_s;
  125.                char *_o_l_d_V_a_l_u_e;
  126.                char *_n_e_w_V_a_l_u_e;
  127.           {
  128.  
  129.  
  130.  
  131. Sprite v.1.0         Printed:  July 31, 1990                    2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. Tcl_TraceVar      Tcl Command Language Library       Tcl_TraceVar
  139.  
  140.  
  141.  
  142.           }
  143.      The _c_l_i_e_n_t_D_a_t_a, _i_n_t_e_r_p, and _v_a_r_N_a_m_e parameters will have the
  144.      same  values  as those passed to TTccll__TTrraacceeVVaarr when the trace
  145.      was   created.    _C_l_i_e_n_t_D_a_t_a   typically   points   to    an
  146.      application-specific  data  structure that describes what to
  147.      do when _p_r_o_c is invoked.  _G_l_o_b_a_l indicates  whether  or  not
  148.      the  variable  is a global one;  it may be needed by _p_r_o_c if
  149.      _p_r_o_c calls TTccll__GGeettVVaarr or TTccll__SSeettVVaarr.   The  _f_l_a_g_s  parameter
  150.      will have one of the bits TCL_TRACE_READS, TCL_TRACE_WRITES,
  151.      or TCL_TRACE_DELETES set;  this indicates which operation is
  152.      being  performed  on  the  variable.   In  addition, the bit
  153.      corresponding to TCL_VARIABLE_UNDEFINED will be set in _f_l_a_g_s
  154.      if  the  variable has never been assigned a value.  _O_l_d_V_a_l_u_e
  155.      gives the variable's current value;  it points to  an  empty
  156.      string if TCL_VARIABLE_UNDEFINED is set.  _N_e_w_V_a_l_u_e gives the
  157.      new value being stored in the variable, if this is  a  write
  158.      operation;  otherwise it points to an empty string.
  159.  
  160.      For read tracing, the return value from _p_r_o_c  is  the  value
  161.      that  will be returned to the reader;  if _p_r_o_c returns NULL,
  162.      this is a signal to the reader that the  variable  is  unde-
  163.      fined.   _P_r_o_c  may  return  _o_l_d_V_a_l_u_e or something completely
  164.      different, at its discretion.  For write tracing, the return
  165.      value  from  _p_r_o_c  is ignored.  However, it is up to _p_r_o_c to
  166.      change the variable's value, if it wishes to allow the write
  167.      to  proceed.   To do this, _p_r_o_c should call TTccll__SSeettVVaarr.  For
  168.      delete tracing, the return value from _p_r_o_c is also  ignored;
  169.      the  primary  purpose of this trace call is to allow _p_r_o_c to
  170.      free up its data structures associated with the trace.
  171.  
  172.      Tracing is temporarily disabled on the variable  while  _p_r_o_c
  173.      is  executing.  This means that _p_r_o_c may call TTccll__GGeettVVaarr and
  174.      TTccll__SSeettVVaarr without fear of infinite recursion on itself: the
  175.      calls  will  operate  directly  on the variable, as if there
  176.      were no tracing.  Once _p_r_o_c returns the trace is re-enabled.
  177.  
  178.      TTccll__UUnnSSeettTTrraaccee may be used to remove a trace from the  vari-
  179.      able  given  by _i_n_t_e_r_p, _v_a_r_N_a_m_e, and _g_l_o_b_a_l.  If the current
  180.      trace includes TCL_TRACE_DELETES, then the  trace  procedure
  181.      will  be invoked one last time as part of the TTccll__UUnnSSeettTTrraaccee
  182.      call.  If there is currently no trace on the selected  vari-
  183.      able then TTccll__UUnnSSeettTTrraaccee has no effect.
  184.  
  185.      TTccll__VVaarrTTrraacceeIInnffoo is used to find out about the current trace
  186.      on  a variable, if any.  The arguments _p_r_o_c_P_t_r and _c_l_i_e_n_t_D_a_-
  187.      _t_a_P_t_r point to variables that TTccll__VVaarrTTrraacceeIInnffoo fills in with
  188.      the  _p_r_o_c  and  _c_l_i_e_n_t_D_a_t_a arguments (respectively) from the
  189.      call that created the current trace.  The  return  value  is
  190.      the  _f_l_a_g_s  argument  from the call that created the current
  191.      trace.  If there is no trace on the indicated  variable,  or
  192.      if  the  variable  doesn't  exist,  then  0  is returned and
  193.      *_p_r_o_c_P_t_r and *_c_l_i_e_n_t_D_a_t_a_P_t_r are both set to NULL.
  194.  
  195.  
  196.  
  197. Sprite v.1.0         Printed:  July 31, 1990                    3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204. Tcl_TraceVar      Tcl Command Language Library       Tcl_TraceVar
  205.  
  206.  
  207.  
  208. KKEEYYWWOORRDDSS
  209.      clientData, trace, variable
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263. Sprite v.1.0         Printed:  July 31, 1990                    4
  264.  
  265.  
  266.  
  267.